=begin pod :kind("Type") :subkind("class") :category("basic")

=TITLE class ComplexStr

=SUBTITLE Dual value complex number and string

    class ComplexStr is Allomorph is Complex {}

C<ComplexStr> is a dual value type, a subclass of both
L«C<Allomorph>|/type/Allomorph», hence L«C<Str>|/type/Str», and
L«C<Complex>|/type/Complex».

See L«C<Allomorph>|/type/Allomorph» for further details.

=begin code
my $complex-str = <42+0i>;
say $complex-str.^name;             # OUTPUT: «ComplexStr␤»

my Complex $complex = $complex-str; # OK!
my Str     $str     = $complex-str; # OK!

# ∈ operator cares about object identity
say 42+0i ∈ <42+0i  55  1>;         # OUTPUT: «False␤»
=end code

=head1 Methods

=head2 method new

    method new(Complex $i, Str $s)

The constructor requires both the C<Complex> and the C<Str> value, when constructing one
directly the values can be whatever is required:

    my $f = ComplexStr.new(42+0i, "forty two (but complicated)");
    say +$f; # OUTPUT: «42+0i␤»
    say ~$f; # OUTPUT: «"forty two (but complicated)"␤»

=head2 method Capture

Defined as:

    method Capture(ComplexStr:D: --> Capture:D)

Equivalent to L«C<Mu.Capture>|/type/Mu#method_Capture».

=head2 method Complex

    method Complex

Returns the C<Complex> value of the C<ComplexStr>.

=head2 method Numeric

Defined as:

    multi method Numeric(ComplexStr:D: --> Complex:D)
    multi method Numeric(ComplexStr:U: --> Complex:D)

The C<:D> variant returns the numeric portion of the invocant. The C<:U> variant issues
a warning about using an uninitialized value in numeric context and then returns value C«<0+0i>».

=head2 method Real

Defined as:

    multi method Real(ComplexStr:D: --> Num:D)
    multi method Real(ComplexStr:U: --> Num:D)

Coerces the numeric portion of the invocant to L<Num|/type/Num>. If the imaginary part
isn't L<approximately|/routine/=~=> zero,
coercion L<fails|/routine/fail> with C<X::Numeric::Real>.

The C<:D> variant returns the result of that coercion. The C<:U> variant issues
a warning about using an uninitialized value in numeric context and then returns value C<0e0>.

=head1 Operators

=head2 infix C«===»

    multi sub infix:<===>(ComplexStr:D $a, ComplexStr:D $b)

C<ComplexStr> Value identity operator. Returns C<True> if the C<Complex>
values of C<$a> and C<$b> are L<identical|/routine/===> and their C<Str>
values are also L<identical|/routine/===>. Returns C<False> otherwise.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
